매월 마지막 주, 다섯 개 은행 사이트를 돌며 거래내역을 다운받아 본 적 있다면 — 그 시간을 이 글이 돌려줍니다. 같은 일을 Claude Code에 자연어 한 줄로 부탁하면 그만입니다.

이 글은 노트북 앞에서 따라 할 수 있는 단계별 가이드입니다. 처음 셋업이라면 약 10분, 다음번부터는 한 줄.

무엇을 만들 것인가

끝에 손에 쥐는 그림은 이렇습니다. Claude Code 안에서:

> 지난달 국민은행 거래내역 받아서 출금 합계만 알려줘

# 잠시 후 …
거래 47건. 출금 합계 ₩12,840,500.
가장 큰 출금은 4/15 ECOUNT-카드자동납부 ₩487,500.

이 한 줄 뒤에서는 다음이 일어납니다.

Claude Code가 h6s_fetch_data MCP 도구를 호출합니다 (provider=CB_KB, schema=bank.transactions.cb.v1, month=2026-04).
headless 백엔드가 국민은행에서 거래내역을 받아 표준 데이터 형식에 맞춰 응답합니다.
ContractRecord 배열이 Claude Code로 돌아옵니다.
Claude Code가 필요한 집계와 자연어 요약을 만듭니다.

여기까지 가는 데 필요한 준비물 세 가지.

Claude Code가 깔린 노트북
h6s.ai 계정 (없으면 30초)
거래내역을 받을 은행의 공동인증서 (또는 ID·비밀번호)

1. headless 계정과 API key (1분)

h6s.ai 에서 회원가입 후 콘솔로 들어갑니다. API Keys 메뉴에서 새 키를 발급하면 h6s_live_ 로 시작하는 문자열이 나옵니다. 즉시 사용할 수 있습니다.

bash

export H6S_API_KEY=h6s_live_a1b2c3d4...

2. Claude Code 플러그인 설치 (2분)

Claude Code에서 /plugin marketplace 명령으로 headless의 marketplace를 한 번 등록하고, 플러그인을 설치합니다.

/plugin marketplace add bolta-io/h6s-toolkit
/plugin install h6s-data@h6s

설치가 끝나면 Claude Code를 한 번 재시작합니다. 다음 세션부터 h6s_* 도구들이 자연어 호출에 자동으로 노출됩니다.

첫 호출이 느리면 timeout 처럼 보일 수 있습니다. .mcp.json 진입점이 npx -y @h6s-ai/cli 라 처음 한 번 npm cache hydration에 1~2분이 걸립니다. 회피하려면 미리 한 번 npm i -g @h6s-ai/cli 로 글로벌 설치해 두면 됩니다.

3. 자격증명 한 번 등록 (3분)

거래내역을 받으려면 그 은행 계정의 자격증명을 headless에 등록해야 합니다. headless가 자격증명을 봉투 암호화(envelope encryption)로 저장하고, 데이터 수집 시점에만 메모리에서 복호화합니다. 등록 후 평문은 어디에도 남지 않습니다.

가장 빠른 길은 공동인증서입니다. PFX 파일 한 번 등록으로 거의 모든 한국 기업뱅킹과 홈택스에 자동 매칭됩니다. 은행마다 자격증명을 따로 만들 필요가 없습니다.

Claude Code에서 자연어로 부탁하면 됩니다. 단, PFX 비밀번호처럼 민감 값을 Claude Code가 메모리에 잠깐 거쳐 도구 호출로 전달되는 흐름이라 처음 등록 시 한 번 동의 후 진행됩니다.

> headless에 공동인증서 등록해줘. 파일은 ~/Downloads/cert.pfx, 비밀번호는 따로 입력할게.

# Claude Code가 차례로:
# 1. h6s_catalog 호출 → globalCert 입력 폼 fieldKey 확인
# 2. PFX 파일을 읽어 base64 로 인코딩
# 3. 비밀번호는 터미널 secret prompt 로 한 번 입력 (평문이 화면에 안 남음)
# 4. h6s_credentials_create 호출 → { id, credentialHealth: "UNKNOWN" } 반환

공동인증서가 없는 환경이라면 ID·비밀번호로 등록합니다. 같은 도구가 providerCode 만 추가로 받으면 됩니다.

> 신한은행 인터넷뱅킹 ID/비번으로 자격증명 등록할게

등록 후 상태 확인은 h6s_list_credentials 가 받아줍니다.

> headless에 등록된 자격증명 보여줘

자격증명이 살아 있는지는 별도 검증 API가 없습니다. 다음 단계의 데이터 수집을 한 번 돌려서 응답이 정상인지 보면 끝입니다. failureCategory: CREDENTIAL 이 나오면 그때 자격증명 문제로 좁히면 됩니다.

4. 자연어로 첫 호출 (1분)

이제 자연어 한 줄이 동작합니다.

> 지난달 국민은행 거래내역 받아줘

응답은 표준 ContractRecord 배열입니다. bank.transactions.cb.v1 데이터 형식의 8개 필드가 고정되어 있습니다 — transactionAt · accountNumber · accountNumberFormatted · accountType · currencyCode · amount · description · balance.

json

{
  "schemaId": "bank.transactions.cb.v1",
  "transactionAt": "2026-04-15T14:32:00+09:00",
  "accountNumber": "11012345671234",
  "accountNumberFormatted": "110-1234-5671-234",
  "accountType": "CHECKING",
  "currencyCode": "KRW",
  "amount": -487500,
  "description": "ECOUNT-카드자동납부",
  "balance": 12340500
}

어느 은행에서 받아도 셰이프가 같습니다. 코드를 그대로 쓰면 됩니다.

5. 그 다음은 자연어 일거리

거래내역이 손에 들어오면 그 위에서 자연어로 거의 모든 후처리를 부탁할 수 있습니다.

> 이 거래내역에서 "ECOUNT" 가 들어간 출금만 모아서 CSV로 저장해줘
> 이번 달 50만원 이상 입금만 모아서 CSV로 저장해줘
> 5만원 이상 입금 중에 거래 상대가 처음 보이는 것만 알려줘

같은 흐름이 세금계산서(hometax.tax-invoices.sales.v1) 와 현금영수증(hometax.cash-receipts.sales.v1) 에도 그대로 적용됩니다. 데이터 형식 이름만 바꿔 부르면 됩니다.

자주 만나는 막힘

증상	원인	대응
첫 호출이 timeout 처럼 멈춤	npm cache hydration (1~2분)	미리 `npm i -g @h6s-ai/cli` 로 글로벌 설치
`CREDENTIAL_NOT_FOUND`	자격증명 미등록 또는 provider 매칭 실패	`h6s_list_credentials` 로 등록 상태 확인
`INVALID_CREDENTIALS`	PFX 비밀번호 또는 ID/비번 오류	콘솔에서 자격증명 갱신
`failureCategory: CREDENTIAL`	등록은 됐지만 은행이 거부 (만료·이상로그인 등)	콘솔에서 자격증명 갱신 또는 재등록
응답이 비어 있음	해당 월에 거래가 없거나 계좌가 매칭되지 않음	`params.bankAccountNumber` 명시해서 재시도

더 깊이

첫 호출이 잘 됐다면 다음은 Claude Code 통합을 더 파고들 차례입니다. Claude Code 연동 문서에 자격증명·데이터 형식·트러블슈팅이 한곳에 있습니다.